<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Threads</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
<link rel="home" href="index.html" title="GDK Reference Manual">
<link rel="up" href="reference.html" title="API Reference">
<link rel="prev" href="gdk-Properties-and-Atoms.html" title="Properties and Atoms">
<link rel="next" href="gdk-Input.html" title="Input">
<meta name="generator" content="GTK-Doc V1.11 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="reference" href="reference.html" title="API Reference">
<link rel="index" href="api-index-full.html" title="Index of all symbols">
<link rel="index" href="api-index-deprecated.html" title="Index of deprecated symbols">
<link rel="index" href="api-index-2-2.html" title="Index of new symbols in 2.2">
<link rel="index" href="api-index-2-4.html" title="Index of new symbols in 2.4">
<link rel="index" href="api-index-2-6.html" title="Index of new symbols in 2.6">
<link rel="index" href="api-index-2-8.html" title="Index of new symbols in 2.8">
<link rel="index" href="api-index-2-10.html" title="Index of new symbols in 2.10">
<link rel="index" href="api-index-2-12.html" title="Index of new symbols in 2.12">
<link rel="index" href="api-index-2-14.html" title="Index of new symbols in 2.14">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
<tr valign="middle">
<td><a accesskey="p" href="gdk-Properties-and-Atoms.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="reference.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">GDK Reference Manual</th>
<td><a accesskey="n" href="gdk-Input.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr>
<tr><td colspan="5" class="shortcuts">
<a href="#gdk-Threads.synopsis" class="shortcut">Top</a>
                 | 
                <a href="#gdk-Threads.description" class="shortcut">Description</a>
</td></tr>
</table>
<div class="refentry" lang="en">
<a name="gdk-Threads"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle"><a name="gdk-Threads.top_of_page"></a>Threads</span></h2>
<p>Threads — Functions for using GDK in multi-threaded programs</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsynopsisdiv">
<a name="gdk-Threads.synopsis"></a><h2>Synopsis</h2>
<pre class="synopsis">

#include &lt;gdk/gdk.h&gt;

#define             <a class="link" href="gdk-Threads.html#GDK-THREADS-ENTER--CAPS" title="GDK_THREADS_ENTER()">GDK_THREADS_ENTER</a>                   ()
#define             <a class="link" href="gdk-Threads.html#GDK-THREADS-LEAVE--CAPS" title="GDK_THREADS_LEAVE()">GDK_THREADS_LEAVE</a>                   ()
void                <a class="link" href="gdk-Threads.html#gdk-threads-init" title="gdk_threads_init ()">gdk_threads_init</a>                    (void);
void                <a class="link" href="gdk-Threads.html#gdk-threads-enter" title="gdk_threads_enter ()">gdk_threads_enter</a>                   (void);
void                <a class="link" href="gdk-Threads.html#gdk-threads-leave" title="gdk_threads_leave ()">gdk_threads_leave</a>                   (void);
extern              GMutex *<a class="link" href="gdk-Threads.html#gdk-threads-mutex" title="gdk_threads_mutex">gdk_threads_mutex</a>;
void                <a class="link" href="gdk-Threads.html#gdk-threads-set-lock-functions" title="gdk_threads_set_lock_functions ()">gdk_threads_set_lock_functions</a>      (<a
href="/usr/share/gtk-doc/html/gobject/gobject-Closures.html#GCallback"
>GCallback</a> enter_fn,
                                                         <a
href="/usr/share/gtk-doc/html/gobject/gobject-Closures.html#GCallback"
>GCallback</a> leave_fn);
<a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#guint"
>guint</a>               <a class="link" href="gdk-Threads.html#gdk-threads-add-idle" title="gdk_threads_add_idle ()">gdk_threads_add_idle</a>                (<a
href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#GSourceFunc"
>GSourceFunc</a> function,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gpointer"
>gpointer</a> data);
<a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#guint"
>guint</a>               <a class="link" href="gdk-Threads.html#gdk-threads-add-idle-full" title="gdk_threads_add_idle_full ()">gdk_threads_add_idle_full</a>           (<a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gint"
>gint</a> priority,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#GSourceFunc"
>GSourceFunc</a> function,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gpointer"
>gpointer</a> data,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-Datasets.html#GDestroyNotify"
>GDestroyNotify</a> notify);
<a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#guint"
>guint</a>               <a class="link" href="gdk-Threads.html#gdk-threads-add-timeout" title="gdk_threads_add_timeout ()">gdk_threads_add_timeout</a>             (<a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#guint"
>guint</a> interval,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#GSourceFunc"
>GSourceFunc</a> function,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gpointer"
>gpointer</a> data);
<a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#guint"
>guint</a>               <a class="link" href="gdk-Threads.html#gdk-threads-add-timeout-full" title="gdk_threads_add_timeout_full ()">gdk_threads_add_timeout_full</a>        (<a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gint"
>gint</a> priority,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#guint"
>guint</a> interval,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#GSourceFunc"
>GSourceFunc</a> function,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gpointer"
>gpointer</a> data,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-Datasets.html#GDestroyNotify"
>GDestroyNotify</a> notify);
<a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#guint"
>guint</a>               <a class="link" href="gdk-Threads.html#gdk-threads-add-timeout-seconds" title="gdk_threads_add_timeout_seconds ()">gdk_threads_add_timeout_seconds</a>     (<a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#guint"
>guint</a> interval,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#GSourceFunc"
>GSourceFunc</a> function,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gpointer"
>gpointer</a> data);
<a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#guint"
>guint</a>               <a class="link" href="gdk-Threads.html#gdk-threads-add-timeout-seconds-full" title="gdk_threads_add_timeout_seconds_full ()">gdk_threads_add_timeout_seconds_full</a>
                                                        (<a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gint"
>gint</a> priority,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#guint"
>guint</a> interval,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#GSourceFunc"
>GSourceFunc</a> function,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gpointer"
>gpointer</a> data,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-Datasets.html#GDestroyNotify"
>GDestroyNotify</a> notify);
</pre>
</div>
<div class="refsect1" lang="en">
<a name="gdk-Threads.description"></a><h2>Description</h2>
<p>
For thread safety, GDK relies on the thread primitives in GLib,
and on the thread-safe GLib main loop.
</p>
<p>
GLib is completely thread safe (all global data is automatically
locked), but individual data structure instances are not automatically
locked for performance reasons. So e.g. you must coordinate
accesses to the same <a
href="/usr/share/gtk-doc/html/glib/glib-Hash-Tables.html#GHashTable"
><span class="type">GHashTable</span></a> from multiple threads.
</p>
<p>
GTK+ is "thread aware" but not thread safe — it provides a
global lock controlled by <a class="link" href="gdk-Threads.html#gdk-threads-enter" title="gdk_threads_enter ()"><code class="function">gdk_threads_enter()</code></a>/<a class="link" href="gdk-Threads.html#gdk-threads-leave" title="gdk_threads_leave ()"><code class="function">gdk_threads_leave()</code></a>
which protects all use of GTK+. That is, only one thread can use GTK+
at any given time.
</p>
<p>
Unfortunately the above holds with the X11 backend only. With the
Win32 backend, GDK calls should not be attempted from multiple threads
at all.
</p>
<p>
You must call <a
href="/usr/share/gtk-doc/html/glib/glib-Threads.html#g-thread-init"
><code class="function">g_thread_init()</code></a> and <a class="link" href="gdk-Threads.html#gdk-threads-init" title="gdk_threads_init ()"><code class="function">gdk_threads_init()</code></a> before executing
any other GTK+ or GDK functions in a threaded GTK+ program.
</p>
<p>
Idles, timeouts, and input functions from GLib, such as <a
href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#g-idle-add"
><code class="function">g_idle_add()</code></a>, are
executed outside of the main GTK+ lock.
So, if you need to call GTK+ inside of such a callback, you must surround
the callback with a <a class="link" href="gdk-Threads.html#gdk-threads-enter" title="gdk_threads_enter ()"><code class="function">gdk_threads_enter()</code></a>/<a class="link" href="gdk-Threads.html#gdk-threads-leave" title="gdk_threads_leave ()"><code class="function">gdk_threads_leave()</code></a> pair or use
<a class="link" href="gdk-Threads.html#gdk-threads-add-idle-full" title="gdk_threads_add_idle_full ()"><code class="function">gdk_threads_add_idle_full()</code></a> which does this for you.
However, event dispatching from the mainloop is still executed within
the main GTK+ lock, so callback functions connected to event signals
like GtkWidget::button-press-event, do not need thread protection.
</p>
<p>
In particular, this means, if you are writing widgets that might
be used in threaded programs, you <span class="emphasis"><em>must</em></span> surround
timeouts and idle functions in this matter.
</p>
<p>
As always, you must also surround any calls to GTK+ not made within
a signal handler with a <a class="link" href="gdk-Threads.html#gdk-threads-enter" title="gdk_threads_enter ()"><code class="function">gdk_threads_enter()</code></a>/<a class="link" href="gdk-Threads.html#gdk-threads-leave" title="gdk_threads_leave ()"><code class="function">gdk_threads_leave()</code></a> pair.
</p>
<p>
Before calling <a class="link" href="gdk-Threads.html#gdk-threads-leave" title="gdk_threads_leave ()"><code class="function">gdk_threads_leave()</code></a> from a thread other
than your main thread, you probably want to call <a class="link" href="gdk-General.html#gdk-flush" title="gdk_flush ()"><code class="function">gdk_flush()</code></a>
to send all pending commands to the windowing system.
(The reason you don't need to do this from the main thread
is that GDK always automatically flushes pending commands
when it runs out of incoming events to process and has
to sleep while waiting for more events.)
</p>
<p>A minimal main program for a threaded GTK+ application
looks like:</p>
<div class="informalexample"><pre class="programlisting">
int
main (int argc, char *argv[])
{
  GtkWidget *window;
  g_thread_init (NULL);
  gdk_threads_init ();
  gdk_threads_enter ();
  gtk_init (&amp;argc, &amp;argv);
  window = create_window ();
  gtk_widget_show (window);
  gtk_main ();
  gdk_threads_leave ();
  return 0;
}
</pre></div>
<p>
Callbacks require a bit of attention. Callbacks from GTK+ signals
are made within the GTK+ lock. However callbacks from GLib (timeouts,
IO callbacks, and idle functions) are made outside of the GTK+
lock. So, within a signal handler you do not need to call
<a class="link" href="gdk-Threads.html#gdk-threads-enter" title="gdk_threads_enter ()"><code class="function">gdk_threads_enter()</code></a>, but within the other types of callbacks, you
do.
</p>
<p>Erik Mouw contributed the following code example to
illustrate how to use threads within GTK+ programs.
</p>
<div class="informalexample"><pre class="programlisting">
/*-------------------------------------------------------------------------
 * Filename:      gtk-thread.c
 * Version:       0.99.1
 * Copyright:     Copyright (C) 1999, Erik Mouw
 * Author:        Erik Mouw &lt;J.A.K.Mouw@its.tudelft.nl&gt;
 * Description:   GTK threads example.
 * Created at:    Sun Oct 17 21:27:09 1999
 * Modified by:   Erik Mouw &lt;J.A.K.Mouw@its.tudelft.nl&gt;
 * Modified at:   Sun Oct 24 17:21:41 1999
 *-----------------------------------------------------------------------*/
/*
 * Compile with:
 *
 * cc -o gtk-thread gtk-thread.c `gtk-config --cflags --libs gthread`
 *
 * Thanks to Sebastian Wilhelmi and Owen Taylor for pointing out some
 * bugs.
 *
 */
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;unistd.h&gt;
#include &lt;time.h&gt;
#include &lt;gtk/gtk.h&gt;
#include &lt;glib.h&gt;
#include &lt;pthread.h&gt;
#define YES_IT_IS    (1)
#define NO_IT_IS_NOT (0)
typedef struct
{
  GtkWidget *label;
  int what;
} yes_or_no_args;
G_LOCK_DEFINE_STATIC (yes_or_no);
static volatile int yes_or_no = YES_IT_IS;
void destroy (GtkWidget *widget, gpointer data)
{
  gtk_main_quit ();
}
void *argument_thread (void *args)
{
  yes_or_no_args *data = (yes_or_no_args *)args;
  gboolean say_something;
  for (;;)
    {
      /* sleep a while */
      sleep(rand() / (RAND_MAX / 3) + 1);
      /* lock the yes_or_no_variable */
      G_LOCK(yes_or_no);
      /* do we have to say something? */
      say_something = (yes_or_no != data-&gt;what);
      if(say_something)
	{
	  /* set the variable */
	  yes_or_no = data-&gt;what;
	}
      /* Unlock the yes_or_no variable */
      G_UNLOCK (yes_or_no);
      if (say_something)
	{
	  /* get GTK thread lock */
	  gdk_threads_enter ();
	  /* set label text */
	  if(data-&gt;what == YES_IT_IS)
	    gtk_label_set_text (GTK_LABEL (data-&gt;label), "O yes, it is!");
	  else
	    gtk_label_set_text (GTK_LABEL (data-&gt;label), "O no, it isn't!");
	  /* release GTK thread lock */
	  gdk_threads_leave ();
	}
    }
  return NULL;
}
int main (int argc, char *argv[])
{
  GtkWidget *window;
  GtkWidget *label;
  yes_or_no_args yes_args, no_args;
  pthread_t no_tid, yes_tid;
  /* init threads */
  g_thread_init (NULL);
  gdk_threads_init ();
  gdk_threads_enter ();
  /* init gtk */
  gtk_init(&amp;argc, &amp;argv);
  /* init random number generator */
  srand ((unsigned int) time (NULL));
  /* create a window */
  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  gtk_signal_connect (GTK_OBJECT (window), "destroy",
		      GTK_SIGNAL_FUNC (destroy), NULL);
  gtk_container_set_border_width (GTK_CONTAINER (window), 10);
  /* create a label */
  label = gtk_label_new ("And now for something completely different ...");
  gtk_container_add (GTK_CONTAINER (window), label);
  /* show everything */
  gtk_widget_show (label);
  gtk_widget_show (window);
  /* create the threads */
  yes_args.label = label;
  yes_args.what = YES_IT_IS;
  pthread_create (&amp;yes_tid, NULL, argument_thread, &amp;yes_args);
  no_args.label = label;
  no_args.what = NO_IT_IS_NOT;
  pthread_create (&amp;no_tid, NULL, argument_thread, &amp;no_args);
  /* enter the GTK main loop */
  gtk_main ();
  gdk_threads_leave ();
  return 0;
}
</pre></div>
</div>
<div class="refsect1" lang="en">
<a name="gdk-Threads.details"></a><h2>Details</h2>
<div class="refsect2" lang="en">
<a name="GDK-THREADS-ENTER--CAPS"></a><h3>GDK_THREADS_ENTER()</h3>
<pre class="programlisting">#define             GDK_THREADS_ENTER()</pre>
<p>
This macro marks the beginning of a critical section in which GDK and
GTK+ functions can be called safely and without causing race
conditions.  Only one thread at a time can be in such a critial
section. The macro expands to a no-op if <a
href="/usr/share/gtk-doc/html/glib/glib-Threads.html#G-THREADS-ENABLED--CAPS"
><span class="type">G_THREADS_ENABLED</span></a> has not
been defined. Typically <a class="link" href="gdk-Threads.html#gdk-threads-enter" title="gdk_threads_enter ()"><code class="function">gdk_threads_enter()</code></a> should be used instead of
this macro.
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="GDK-THREADS-LEAVE--CAPS"></a><h3>GDK_THREADS_LEAVE()</h3>
<pre class="programlisting">#define             GDK_THREADS_LEAVE()</pre>
<p>
This macro marks the end of a critical section
begun with <a class="link" href="gdk-Threads.html#GDK-THREADS-ENTER--CAPS" title="GDK_THREADS_ENTER()"><span class="type">GDK_THREADS_ENTER</span></a>.
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="gdk-threads-init"></a><h3>gdk_threads_init ()</h3>
<pre class="programlisting">void                gdk_threads_init                    (void);</pre>
<p>
Initializes GDK so that it can be used from multiple threads
in conjunction with <a class="link" href="gdk-Threads.html#gdk-threads-enter" title="gdk_threads_enter ()"><code class="function">gdk_threads_enter()</code></a> and <a class="link" href="gdk-Threads.html#gdk-threads-leave" title="gdk_threads_leave ()"><code class="function">gdk_threads_leave()</code></a>.
<a
href="/usr/share/gtk-doc/html/glib/glib-Threads.html#g-thread-init"
><code class="function">g_thread_init()</code></a> must be called previous to this function.
</p>
<p>
This call must be made before any use of the main loop from
GTK+; to be safe, call it before <a
href="/usr/share/gtk-doc/html/gtk/gtk-General.html#gtk-init"
><code class="function">gtk_init()</code></a>.</p>
<p>
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="gdk-threads-enter"></a><h3>gdk_threads_enter ()</h3>
<pre class="programlisting">void                gdk_threads_enter                   (void);</pre>
<p>
This macro marks the beginning of a critical section in which GDK and
GTK+ functions can be called safely and without causing race
conditions.  Only one thread at a time can be in such a critial
section.
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="gdk-threads-leave"></a><h3>gdk_threads_leave ()</h3>
<pre class="programlisting">void                gdk_threads_leave                   (void);</pre>
<p>
Leaves a critical region begun with <a class="link" href="gdk-Threads.html#gdk-threads-enter" title="gdk_threads_enter ()"><code class="function">gdk_threads_enter()</code></a>.
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="gdk-threads-mutex"></a><h3>gdk_threads_mutex</h3>
<pre class="programlisting">extern GMutex *gdk_threads_mutex; /* private */
</pre>
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Warning</h3>
<p><code class="literal">gdk_threads_mutex</code> is deprecated and should not be used in newly-written code.</p>
</div>
<p>
The <a
href="/usr/share/gtk-doc/html/glib/glib-Threads.html#GMutex"
><span class="type">GMutex</span></a> used to implement the critical region for
<a class="link" href="gdk-Threads.html#gdk-threads-enter" title="gdk_threads_enter ()"><code class="function">gdk_threads_enter()</code></a>/<a class="link" href="gdk-Threads.html#gdk-threads-leave" title="gdk_threads_leave ()"><code class="function">gdk_threads_leave()</code></a>.
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="gdk-threads-set-lock-functions"></a><h3>gdk_threads_set_lock_functions ()</h3>
<pre class="programlisting">void                gdk_threads_set_lock_functions      (<a
href="/usr/share/gtk-doc/html/gobject/gobject-Closures.html#GCallback"
>GCallback</a> enter_fn,
                                                         <a
href="/usr/share/gtk-doc/html/gobject/gobject-Closures.html#GCallback"
>GCallback</a> leave_fn);</pre>
<p>
Allows the application to replace the standard method that
GDK uses to protect its data structures. Normally, GDK
creates a single <a
href="/usr/share/gtk-doc/html/glib/glib-Threads.html#GMutex"
><span class="type">GMutex</span></a> that is locked by <a class="link" href="gdk-Threads.html#gdk-threads-enter" title="gdk_threads_enter ()"><code class="function">gdk_threads_enter()</code></a>,
and released by <a class="link" href="gdk-Threads.html#gdk-threads-leave" title="gdk_threads_leave ()"><code class="function">gdk_threads_leave()</code></a>; using this function an
application provides, instead, a function <em class="parameter"><code>enter_fn</code></em> that is
called by <a class="link" href="gdk-Threads.html#gdk-threads-enter" title="gdk_threads_enter ()"><code class="function">gdk_threads_enter()</code></a> and a function <em class="parameter"><code>leave_fn</code></em> that is
called by <a class="link" href="gdk-Threads.html#gdk-threads-leave" title="gdk_threads_leave ()"><code class="function">gdk_threads_leave()</code></a>.
</p>
<p>
The functions must provide at least same locking functionality
as the default implementation, but can also do extra application
specific processing.
</p>
<p>
As an example, consider an application that has its own recursive
lock that when held, holds the GTK+ lock as well. When GTK+ unlocks
the GTK+ lock when entering a recursive main loop, the application
must temporarily release its lock as well.
</p>
<p>
Most threaded GTK+ apps won't need to use this method.
</p>
<p>
This method must be called before <a class="link" href="gdk-Threads.html#gdk-threads-init" title="gdk_threads_init ()"><code class="function">gdk_threads_init()</code></a>, and cannot
be called multiple times.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>enter_fn</code></em> :</span></p></td>
<td>   function called to guard GDK
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>leave_fn</code></em> :</span></p></td>
<td> function called to release the guard
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.4</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="gdk-threads-add-idle"></a><h3>gdk_threads_add_idle ()</h3>
<pre class="programlisting"><a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#guint"
>guint</a>               gdk_threads_add_idle                (<a
href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#GSourceFunc"
>GSourceFunc</a> function,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gpointer"
>gpointer</a> data);</pre>
<p>
A wrapper for the common usage of <a class="link" href="gdk-Threads.html#gdk-threads-add-idle-full" title="gdk_threads_add_idle_full ()"><code class="function">gdk_threads_add_idle_full()</code></a> 
assigning the default priority, <a
href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#G-PRIORITY-DEFAULT-IDLE--CAPS"
><span class="type">G_PRIORITY_DEFAULT_IDLE</span></a>.
</p>
<p>
See <a class="link" href="gdk-Threads.html#gdk-threads-add-idle-full" title="gdk_threads_add_idle_full ()"><code class="function">gdk_threads_add_idle_full()</code></a>.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>function</code></em> :</span></p></td>
<td> function to call
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
<td>     data to pass to <em class="parameter"><code>function</code></em>
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> the ID (greater than 0) of the event source.

</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.12</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="gdk-threads-add-idle-full"></a><h3>gdk_threads_add_idle_full ()</h3>
<pre class="programlisting"><a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#guint"
>guint</a>               gdk_threads_add_idle_full           (<a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gint"
>gint</a> priority,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#GSourceFunc"
>GSourceFunc</a> function,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gpointer"
>gpointer</a> data,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-Datasets.html#GDestroyNotify"
>GDestroyNotify</a> notify);</pre>
<p>
Adds a function to be called whenever there are no higher priority
events pending.  If the function returns <a
href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#FALSE--CAPS"
><code class="literal">FALSE</code></a> it is automatically
removed from the list of event sources and will not be called again.
</p>
<p>
This variant of <a
href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#g-idle-add-full"
><code class="function">g_idle_add_full()</code></a> calls <em class="parameter"><code>function</code></em> with the GDK lock
held. It can be thought of a MT-safe version for GTK+ widgets for the 
following use case, where you have to worry about <code class="function">idle_callback()</code>
running in thread A and accessing <em class="parameter"><code>self</code></em> after it has been finalized
in thread B:
</p>
<p>
</p>
<div class="informalexample"><pre class="programlisting">
static gboolean
idle_callback (gpointer data)
{
   /* gdk_threads_enter(); would be needed for g_idle_add() */

   SomeWidget *self = data;
   /* do stuff with self */

   self-&gt;idle_id = 0;

   /* gdk_threads_leave(); would be needed for g_idle_add() */
   return FALSE;
}

static void
some_widget_do_stuff_later (SomeWidget *self)
{
   self-&gt;idle_id = gdk_threads_add_idle (idle_callback, self)
   /* using g_idle_add() here would require thread protection in the callback */
}

static void
some_widget_finalize (GObject *object)
{
   SomeWidget *self = SOME_WIDGET (object);
   if (self-&gt;idle_id)
     g_source_remove (self-&gt;idle_id);
   G_OBJECT_CLASS (parent_class)-&gt;finalize (object);
}
</pre></div>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>priority</code></em> :</span></p></td>
<td> the priority of the idle source. Typically this will be in the
           range btweeen <a
href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#G-PRIORITY-DEFAULT-IDLE--CAPS"
><span class="type">G_PRIORITY_DEFAULT_IDLE</span></a> and <a
href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#G-PRIORITY-HIGH-IDLE--CAPS"
><span class="type">G_PRIORITY_HIGH_IDLE</span></a>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>function</code></em> :</span></p></td>
<td> function to call
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
<td>     data to pass to <em class="parameter"><code>function</code></em>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>notify</code></em> :</span></p></td>
<td>   function to call when the idle is removed, or <a
href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#NULL--CAPS"
><code class="literal">NULL</code></a>
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> the ID (greater than 0) of the event source.

</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.12</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="gdk-threads-add-timeout"></a><h3>gdk_threads_add_timeout ()</h3>
<pre class="programlisting"><a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#guint"
>guint</a>               gdk_threads_add_timeout             (<a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#guint"
>guint</a> interval,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#GSourceFunc"
>GSourceFunc</a> function,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gpointer"
>gpointer</a> data);</pre>
<p>
A wrapper for the common usage of <a class="link" href="gdk-Threads.html#gdk-threads-add-timeout-full" title="gdk_threads_add_timeout_full ()"><code class="function">gdk_threads_add_timeout_full()</code></a> 
assigning the default priority, <a
href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#G-PRIORITY-DEFAULT--CAPS"
><span class="type">G_PRIORITY_DEFAULT</span></a>.
</p>
<p>
See <a class="link" href="gdk-Threads.html#gdk-threads-add-timeout-full" title="gdk_threads_add_timeout_full ()"><code class="function">gdk_threads_add_timeout_full()</code></a>.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>interval</code></em> :</span></p></td>
<td> the time between calls to the function, in milliseconds
            (1/1000ths of a second)
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>function</code></em> :</span></p></td>
<td> function to call
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
<td>     data to pass to <em class="parameter"><code>function</code></em>
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> the ID (greater than 0) of the event source.

</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.12</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="gdk-threads-add-timeout-full"></a><h3>gdk_threads_add_timeout_full ()</h3>
<pre class="programlisting"><a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#guint"
>guint</a>               gdk_threads_add_timeout_full        (<a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gint"
>gint</a> priority,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#guint"
>guint</a> interval,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#GSourceFunc"
>GSourceFunc</a> function,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gpointer"
>gpointer</a> data,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-Datasets.html#GDestroyNotify"
>GDestroyNotify</a> notify);</pre>
<p>
Sets a function to be called at regular intervals holding the GDK lock,
with the given priority.  The function is called repeatedly until it 
returns <a
href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#FALSE--CAPS"
><code class="literal">FALSE</code></a>, at which point the timeout is automatically destroyed 
and the function will not be called again.  The <em class="parameter"><code>notify</code></em> function is
called when the timeout is destroyed.  The first call to the
function will be at the end of the first <em class="parameter"><code>interval</code></em>.
</p>
<p>
Note that timeout functions may be delayed, due to the processing of other
event sources. Thus they should not be relied on for precise timing.
After each call to the timeout function, the time of the next
timeout is recalculated based on the current time and the given interval
(it does not try to 'catch up' time lost in delays).
</p>
<p>
This variant of <a
href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#g-timeout-add-full"
><code class="function">g_timeout_add_full()</code></a> can be thought of a MT-safe version 
for GTK+ widgets for the following use case:
</p>
<p>
</p>
<div class="informalexample"><pre class="programlisting">
static gboolean timeout_callback (gpointer data)
{
   SomeWidget *self = data;
   
   /* do stuff with self */
   
   self-&gt;timeout_id = 0;
   
   return FALSE;
}
 
static void some_widget_do_stuff_later (SomeWidget *self)
{
   self-&gt;timeout_id = g_timeout_add (timeout_callback, self)
}
 
static void some_widget_finalize (GObject *object)
{
   SomeWidget *self = SOME_WIDGET (object);
   
   if (self-&gt;timeout_id)
     g_source_remove (self-&gt;timeout_id);
   
   G_OBJECT_CLASS (parent_class)-&gt;finalize (object);
}
</pre></div>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>priority</code></em> :</span></p></td>
<td> the priority of the timeout source. Typically this will be in the
           range between <a
href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#G-PRIORITY-DEFAULT-IDLE--CAPS"
><span class="type">G_PRIORITY_DEFAULT_IDLE</span></a> and <a
href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#G-PRIORITY-HIGH-IDLE--CAPS"
><span class="type">G_PRIORITY_HIGH_IDLE</span></a>.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>interval</code></em> :</span></p></td>
<td> the time between calls to the function, in milliseconds
            (1/1000ths of a second)
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>function</code></em> :</span></p></td>
<td> function to call
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
<td>     data to pass to <em class="parameter"><code>function</code></em>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>notify</code></em> :</span></p></td>
<td>   function to call when the timeout is removed, or <a
href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#NULL--CAPS"
><code class="literal">NULL</code></a>
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> the ID (greater than 0) of the event source.

</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.12</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="gdk-threads-add-timeout-seconds"></a><h3>gdk_threads_add_timeout_seconds ()</h3>
<pre class="programlisting"><a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#guint"
>guint</a>               gdk_threads_add_timeout_seconds     (<a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#guint"
>guint</a> interval,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#GSourceFunc"
>GSourceFunc</a> function,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gpointer"
>gpointer</a> data);</pre>
<p>
A wrapper for the common usage of <a class="link" href="gdk-Threads.html#gdk-threads-add-timeout-seconds-full" title="gdk_threads_add_timeout_seconds_full ()"><code class="function">gdk_threads_add_timeout_seconds_full()</code></a> 
assigning the default priority, <a
href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#G-PRIORITY-DEFAULT--CAPS"
><span class="type">G_PRIORITY_DEFAULT</span></a>.
</p>
<p>
For details, see <a class="link" href="gdk-Threads.html#gdk-threads-add-timeout-full" title="gdk_threads_add_timeout_full ()"><code class="function">gdk_threads_add_timeout_full()</code></a>.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>interval</code></em> :</span></p></td>
<td> the time between calls to the function, in seconds
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>function</code></em> :</span></p></td>
<td> function to call
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
<td>     data to pass to <em class="parameter"><code>function</code></em>
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> the ID (greater than 0) of the event source.

</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.14</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="gdk-threads-add-timeout-seconds-full"></a><h3>gdk_threads_add_timeout_seconds_full ()</h3>
<pre class="programlisting"><a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#guint"
>guint</a>               gdk_threads_add_timeout_seconds_full
                                                        (<a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gint"
>gint</a> priority,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#guint"
>guint</a> interval,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#GSourceFunc"
>GSourceFunc</a> function,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gpointer"
>gpointer</a> data,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-Datasets.html#GDestroyNotify"
>GDestroyNotify</a> notify);</pre>
<p>
A variant of <code class="function">gdk_threads_add_timout_full()</code> with second-granularity.
See <a
href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#g-timeout-add-seconds-full"
><code class="function">g_timeout_add_seconds_full()</code></a> for a discussion of why it is
a good idea to use this function if you don't need finer granularity.</p>
<p>
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>priority</code></em> :</span></p></td>
<td> the priority of the timeout source. Typically this will be in the
           range between <a
href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#G-PRIORITY-DEFAULT-IDLE--CAPS"
><span class="type">G_PRIORITY_DEFAULT_IDLE</span></a> and <a
href="/usr/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html#G-PRIORITY-HIGH-IDLE--CAPS"
><span class="type">G_PRIORITY_HIGH_IDLE</span></a>.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>interval</code></em> :</span></p></td>
<td> the time between calls to the function, in seconds
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>function</code></em> :</span></p></td>
<td> function to call
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
<td>     data to pass to <em class="parameter"><code>function</code></em>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>notify</code></em> :</span></p></td>
<td>   function to call when the timeout is removed, or <a
href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#NULL--CAPS"
><code class="literal">NULL</code></a>
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> the ID (greater than 0) of the event source.

</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.14</p>
</div>
</div>
</div>
<div class="footer">
<hr>
          Generated by GTK-Doc V1.11</div>
</body>
</html>
